Skip to content

rtsdiff circular: keep only the posterior branch rule, replace innovation_fn with circular - #242

Merged
pavelkomarov merged 5 commits into
masterfrom
circular-posterior-only
Nov 19, 2026
Merged

pavelkomarov merged 5 commits into
masterfrom
circular-posterior-only

Conversation

@pavelkomarov

@pavelkomarov pavelkomarov commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Follow-up to #241, opened for discussion before merging. #241 fixed #240 by choosing each measurement's 2π branch relative to the previous posterior rather than the prediction. That's the right fix, and this PR keeps it. What it removes is the machinery for keeping the old prediction-branch rule around, because I couldn't find a case where that rule is better.

Changes

  • kalman_filter: innovation_fn is replaced by circular. The only innovation_fn we ever used was the angle wrap, and that's exactly the rule that causes rtsdiff(circular=True) can runaway on an aliased solution #240. This is a breaking change to a public argument that shipped in v0.3 (and is named in the JOSS paper, which describes v0.3), so it should go in the release notes.
  • The branch choice is now two lines: innovation -= 2π·round((yₙ − C x̂ₙ₋₁|ₙ₋₁)/2π). It shifts the measurement by whole turns to lie within π of the previous posterior. Missing data needs no special handling, because after a gap the previous posterior is the prediction. This also drops the ValueError for combining circular with innovation_fn.
  • rtsdiff: circular_branch is removed, along with its validation and the **wrapping dict. Docstrings are shortened to match, and circular no longer claims the innovation is wrapped to [−π, π].
  • Tests: the six tests from rtsdiff circular: choose the 2π branch from the previous posterior (fixes #240) #241 (~90 lines) are removed. The issue's own example (a 2 rad step at order 2, log_qr_ratio 12) is now a two-line check inside the existing test_circular_rtsdiff, so it runs with and without forwardbackward. It fails under the old rule both ways.

The output is identical to master's default 'posterior' rule on 72 combinations: a step, a noisy spin, NaN gaps, and 2D input, at orders 1–3, log_qr_ratio 2, 8 and 12, with and without forwardbackward.

Why the #241 tests can go

Test Why it isn't needed
test_circular_step_no_aliasing (8 cases) Kept as the one regression check. The other step sizes and orders trigger the same overshoot.
test_circular_fly_trajectory The real-data version of the step: one large swing at high gain, the same failure.
test_circular_matches_unwrapped (uniform, irregular, missing, 2D) Irregular steps and 2D don't touch the circular code, since the branch choice works one sample at a time. Missing data needs no special code in the new version (after a gap the previous posterior is just the prediction), so the circular-plus-NaN combination isn't separately tested; test_missing_data covers rtsdiff's NaN path without circular.
test_circular_invariant_to_whole_turns True by construction: adding 2πk to a sample shifts the round(...) by exactly k, so the innovation is unchanged.
test_circular_noise_robustness (20 seeds) An experiment rather than a regression check. The sweep below is broader evidence of the same thing.
test_circular_argument_errors Checked validation that no longer exists.
circular_branch parametrization of test_circular_rtsdiff There's only one rule now.

Is there a reason to keep 'prediction'?

#241 kept it on the grounds that it tracks fast, noisy rotation better at low gain. I couldn't find evidence of that:

Notebook 7 (order 1, log_qr_ratio 4): the two rules agree to within 1e-9 on 50 of 50 noise draws, so the notebook's saved outputs stay valid and it needs no rerun. At that gain the prediction never overshoots by more than π, so both rules pick the same branch at every sample.

A gain sweep on notebook 7's data, showing the median dxdt RMSE over 10 noise seeds:

log_qr_ratio 0 2 4 6 8 10 12 14
order 1, prediction 20.7 13.3 3.7 14.8 1259.8 1156.5 1156.5 1156.5
order 1, posterior 16.3 13.3 3.7 14.8 50.1 56.8 56.9 56.9
order 2, prediction 16.7 17.5 29.5 6.0 4.9 855.5 61650.1 78195.1
order 2, posterior 16.7 17.5 12.0 6.0 4.9 15.0 43.1 67.5

The posterior rule is never worse. Where the two rules differ at low gain, the posterior rule is better. At high gain the prediction rule aliases, while the posterior rule only follows the noise, as any high-gain filter would.


🤖 Written by Claude Code on behalf of @pavelkomarov

…tion_fn with circular

#241 fixed #240 by choosing each measurement's 2pi branch relative to the previous posterior, but kept the old prediction-branch rule as circular_branch='prediction' and kept innovation_fn alongside a new circular flag, which forced mutual-exclusion checks and long docstrings. The prediction rule is never better on notebook 7's data at any gain and is the cause of #240, and the only innovation_fn ever used was the angle wrap, so this drops both, makes the branch choice two lines in kalman_filter, and replaces the six #241 tests with one regression test using the issue's own example. Output is identical to master's default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pavelkomarov
pavelkomarov requested a review from florisvb November 3, 2026 16:15
pavelkomarov and others added 3 commits November 3, 2026 16:24
…it also runs with forwardbackward, which the issue noted didn't fix the aliasing

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pavelkomarov
pavelkomarov merged commit d7a1ae0 into master Nov 19, 2026
2 of 3 checks passed
@pavelkomarov
pavelkomarov deleted the circular-posterior-only branch November 19, 2026 13:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

rtsdiff(circular=True) can runaway on an aliased solution

1 participant